<?php
// $Id$
/**
 * This file contains {@link ObservationManager} which is part of the PHP Content 
 * Repository (phpCR), a derivative of the Java Content Repository JSR-170,  
 * and is licensed under the Apache License, Version 2.0.
 *
 * This file is based on the code created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 * @subpackage Level2
 */

/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/../phpCR.library.php');
phpCR::loadInterface('Event', '/event');


/**
 * The ObservationManager object.
 *
 * Level 2 only
 *
 * Acquired via {@link Ticket::getObservationManager()}.
 * Allows for the registration and deregistration of observation listeners.
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @package phpContentRepository
 * @subpackage Level2
 */
interface ObservationManager 
{
   /**
    * Add an observation listener (parameter $listener) which 
    * listens for the specified events that originate from the {@link Item} at
    * $absPath (including all children up to $depth,
    * where -1 indicates an "infinite" depth). 
    *
    * It is possible to register a listener for a path where no {@link Item}
    * currently exists.
    *
    * If $noLocal is TRUE then events generated by 
    * the owning {@link Ticket} are ignored. 
    *
    * To reduce the number of events an observation selector can be specified. 
    * An observation selector discards events that aren't applicable. The 
    * events are selected based on observation content rather than observation 
    * type. This also enables the repository implementation to filter events 
    * before they are dispatched, to reduce bandwidth. 
    *
    * The $eventSelector parameter specifies the expression used 
    ( to filter events. This uses a subset of the ContentSQL  syntax:
    *
    * 
    *   propertyname operator value { ["AND" | "OR"] propertyname operator value}
    * 
    *
    * @param int
    *   A combination of one or more of the following constants encoded as a
    *   bitmask value:
    *   <ul>
    *       <li>{@link EventType::ITEM_ADDED}</li>
    *       <li>{@link EventType::ITEM_CHANGED}</li>
    *       <li>{@link EventType::ITEM_REMOVED}</li>
    *       <li>{@link EventType::ITEM_VERSIONED}</li>
    *       <li>{@link EventType::LABEL_ADDED}</li>
    *       <li>{@link EventType::LABEL_REMOVED}</li>
    *       <li>{@link EventType::ITEM_LOCKED}</li>
    *       <li>{@link EventType::ITEM_UNLOCKED}</li>
    *       <li>{@link EventType::LOCK_EXPIRED}</li>
    *   </ul>
    *   See {@link EventType}.
    * @param string
    *   Specifies the {@link Item} path that the listener wants to receive
    *   events for. It is possible to register a listener for a path where no 
    *   {@link Item} currently exists.
    * @param int
    *   Specifies whether the registration is for the {@link Item} named  by
    *   $absPath ($depth == 0), the {@link Item} and
    *   its immediate children ($depth == 1), or some other depth
    *   of tree. A depth value of -1 corresponds to an "infinite depth", meaning 
    *   the entire sub-tree rooted at $absPath.
    * @param object
    *   An {@link EventListener} object that will "do the listening".
    * @param bool
    *   If TRUE, supresses receipt of events generated by the 
    *   owning {@link Ticket} instance.
    * @param object
    *   An {@link EventSelector} object whose {@link EventSelector::accept()}
    *   method can be used to filter events, based on their content.
    *
    * @throws {@link RepositoryException}
    *   If an error occurs.
    */
    public function addEventListener(
        $eventTypes,
        $absPath,
        $depth,
        EventListener $listener,
        $noLocal,
        EventSelector $selector);
    
    
   /**
    * Same as {@link addEventListener()} except the fourth parameter is a
    * {@link VetoableEventListener} instead of a {@link EventListener}.
    *
    * @see addEventListener()
    *
    * @param int
    * @param string
    *
    * @param int 
    * @param object 
    *   A {@link VetoableEventListener} object.
    * @param bool
    * @param object
    *
    * @throws {@link RepositoryException}
    *   If an error occurs.
    */
    public function addVetoableEventListener(
        $eventTypes,
        $absPath,
        $depth,
        VetoableEventListener $listener,
        $noLocal,
        EventSelector $selector);
    
    
   /**
    * Unregisters an observation listener.
    *
    * A listener may be unregistered while it is being executed. The
    * unregistration method will block until the listener has completed
    * executing. An exception to this rule is a listener which unregisters
    * itself from within the {@link Event::onEvent()} method. In this case, the
    * unregistration method returns immediately, but unregistration will
    * effectively be delayed until the listener completes.
    *
    * @param object
    *   The {@link EventListener} to unregister.
    *
    * @throws {@link RepositoryException} 
    *   If an error occurs.
    */
    public function removeEventListener(EventListener $listener);
    
    
   /**
    * Deregisters a vetoable observation listener.
    *
    * Same as {@link removeEventListener()} except this method's 
    * $listener parameter is derived from 
    * {@link VetoableEventListener}.
    *
    * @see removeEventListener()
    * @param object
    *   The {@link VetoableEventListener} to unregister.
    *
    * @throws {@link RepositoryException}
    *   If an error occurs.
    */
    public function removeVetoableEventListener(VetoableEventListener $listener);
}

